Inside Macintosh: QuickTime
In order for your movies to play, your application must grant time to the Movie Toolbox. You do this by calling the MoviesTask function from your main event loop. The MoviesTask function causes the Movie Toolbox to service all your active movies. You should call this function regularly so that your movie can play smoothly. You can use the UpdateMovie function to force your movie to be redrawn after it has been uncovered.
You may want your application to take a particular action when a movie is done playing. The Movie Toolbox provides the IsMovieDone function, which allows you to determine whether a movie is done playing. The Movie Toolbox also provides more sophisticated callback mechanisms, which are discussed in "Time Base Functions," .
The Movie Toolbox provides two functions that allow your application to determine whether a specified point lies in either a movie or a track. Use the PtInMovie function with movies; use the PtInTrack function with tracks.
Your application can retrieve some status information about movies and tracks. Use the GetMovieStatus function to retrieve movie status; use the GetTrackStatus function to get track status.
The MoviesTask function services active movies.
pascal void MoviesTask (Movie theMovie, long maxMilliSecToUse);
When servicing a movie, the Movie Toolbox performs the processing that is appropriate for the movie--displaying frames, playing sound, reading data from disk, or other tasks. The only time the Movie Toolbox actually draws a movie is during the operation of the MoviesTask function.
You should call MoviesTask as often as possible from your application's main event loop. Note that you should call this function after you have performed your own event processing.
The MoviesTask function services only active movies, and only enabled tracks within those active movies. Use the SetMovieActive function (described on SetMovieActive ) and the SetTrackEnabled function (described on SetTrackEnabled ) to enable and disable movies and tracks.
Note that the MoviesTask function services only your movies. Your application must call the Event Manager's WaitNextEvent routine (or the Event Manager's GetNextEvent routine and the SystemTask routine) to give other applications the opportunity to call MoviesTask for their movies. For details on WaitNextEvent , GetNextEvent , and SystemTask , see Inside Macintosh: Macintosh Toolbox Essentials .
Your application may wish to take a particular action when a movie is done playing. The IsMovieDone function allows you to determine if a particular movie has completely finished playing.
pascal Boolean IsMovieDone (Movie theMovie);
The IsMovieDone function returns true if the specified movie has finished playing; otherwise it returns false . A movie with a positive rate (playing forward) is considered done when its movie time reaches the movie end time. Conversely, a movie with a negative rate (playing backward) is considered done when its movie time reaches the movie start time.
If your application has changed the movie's active segment, the status returned by the IsMovieDone function is relative to the active segment, rather than to the entire movie. You can use the SetMovieActiveSegment function (described on SetMovieActiveSegment ) to change a movie's active segment.
The UpdateMovie function allows your application to ensure that the Movie Toolbox properly displays your movie after it has been uncovered.
Your application should call this function between the Window Manager's BeginUpdate and EndUpdate functions. (For details, see Inside Macintosh: Macintosh Toolbox Essentials .) Do not call MoviesTask at this time. You will observe better display behavior if you call MoviesTask at the end of your update processing.
pascal OSErr UpdateMovie (Movie theMovie);
The UpdateMovie function does not actually update the movie's graphics world. Rather, the function invalidates the movie's display state so that the Movie Toolbox redraws the movie the next time you call the MoviesTask function. If you need to force a movie to be redrawn outside of a Window Manager update sequence, your application can call UpdateMovie and then call the MoviesTask function (described on MoviesTask ) to service the movie.
The Movie Toolbox determines the portion of the screen to update by examining the graphics port's visible region.
For sample code that uses the UpdateMovie function in a Window Manager update sequence, see Listing 13 .
The PtInMovie function allows your application to determine whether a specified point lies in the region defined by a movie's final display boundary region after it has been clipped by the movie's display clipping region. This function is accurate at the current movie time.
pascal Boolean PtInMovie (Movie theMovie, Point pt);
The PtInTrack function allows your application to determine whether a specified point lies in the region defined by a track's display boundary region after it has been clipped by the movie's final display clipping region. This function is accurate at the current movie time.
pascal Boolean PtInTrack (Track theTrack, Point pt);
The GetMovieStatus function searches for errors in all the enabled tracks of the movie. This function returns information about errors that are encountered during the processing associated with the MoviesTask function (described on MoviesTask ). These errors typically reflect playback problems, such as low-memory conditions.
pascal ComponentResult GetMovieStatus (Movie theMovie,
Track *firstProblemTrack);
The GetTrackStatus function returns the value of the last error the media encountered while playing a specified track. This function returns information about errors that are encountered during the processing associated with the MoviesTask function (described on MoviesTask ). These errors typically reflect playback problems, such as low-memory conditions.
The media clears this error code when it detects that the error has been corrected.
pascal ComponentResult GetTrackStatus (Track theTrack);